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What ~exactly~ is deprecation? 


y Developer Platform 


Deprecation and retirement 


First of all, here is our definition of what deprecation and retirement mean to the Twitter API: 


e Deprecation: The feature is no longer supported by the team. No new functionality will be released around that feature, 
and if there are any bugs or issues with the product, the chances that we will explore a fix are extremely low. 


e Retired: The feature will no longer be accessible. 
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Terms vary, but the principles remain 
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The evolution of API capabilities 
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Trust is at the heart of 
deprecation 


Loss of trust with 
developers or end users 
is your single biggest risk 


Avoiding ambiguity 
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Your policy should build developer trust 
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And you get only one shot! 
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The Big 3: Timelines, dependencies, and 
messaging 


1. Achievable, proposed timeline 
for MVP of your next API version 


2. Accounting for limitations and 
dependencies 


5. A clear message crafted for 
customers, with cross-functional 
buy-in 
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Understand the landscape 


e What are industry 
leaders doing? 


e How does your 
capability fit into these O 


standards? 


e Where do you need to 
deviate? 
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Case Study: Deprecating Miro Developer 
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Honesty and transparency above all 


When developers choose to leverage your APIs, they're 
putting their faith in your product, and also your team's 
decision making. 


"[...] when you innovate, you make mistakes. 
It is best to admit them quickly, and get on 
with improving your other innovations." 
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Remain nimble and flexible where necessary 
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Balancing developer focus and commitment 
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Balancing developer focus and commitment 
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Miro Deprecation 
Policy 


A policy that includes 
5 critical components 


1 Concrete timeline and 
communication strategy 


B A commitment to developers that 
they're not alone, with resources to 
help 


E A clear definition of deprecation 
and retirement phases 


miro 


Deprecation policy 


On occasion, Miro may choose to retire a service offered in the Miro Developer Platform. This may be because the 
future roadmap for the service requires breaking changes (thus demanding a new major version), or because the 
service depends on, or relates to, user-facing product capabilities that are being retired. 


As the retirement of a service is a breaking change for applications that depend on it, Miro will provide a minimum of 
6 months' notice before retiring a service. This 6 month period will begin with a “deprecation announcement" that 
communicates our intention to retire a service on a given future date. This announcement will be made through our 
communication channels. We will also attempt to notify the developers of affected apps directly by email on a best 
effort basis. 


The period between a deprecation announcement and the retirement of a service is known as the deprecation 
period. During the deprecation period of a service: 


+ No new features or capabilities will be added to the service 

* No new beta versions or experimental features will be released 

* Requesting a beta version will return the production version 

« Features labeled as experimental will remain so until retirement 

* Only critical security bugs will be addressed, and only in the production version 


Deprecation announcements will be accompanied by guidance on how to respond if your application is impacted by 
the announcement, including a migration guide if a new major version is available or recommendations of alternative 
third-party services where possible. 


Retirement 


At the end of the deprecation period, the service concerned will be retired and no longer be accessible to 
applications. After this date, any attempt to use the service will fail. All documentation for the service will also be 
taken offline. 


If you remember nothing else, remember... 
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eBook Released: API-as- 
a-Product | Nordic APIs 


In our new eBook, API-as-a-Product, we 
cover tips to help you create a working 
business model around a specialized API 
product. Discover common 
monetization models, developer 
marketing tips, and more helpful 
business advice for API-centric SaaS. 


Related topic: 
API-as-a-Product 
eBook by Nordic APIs 
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How to Smartly Sunset 
and Deprecate APIs | 
Nordic APIs | 


Does your API have a retirement plan? 
The best API platforms have consistent 
sunsetting timelines. Discover the best 
practices for deprecating APIs. 


How-To: 

Best practices for 
deprecating APIs, by the 
trusted folks at Nordic APIs 
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Deprecating API 
Endpoints 


Deprecation communicates a function, 
method, or entire package is going away 
or being. How do you warn developers 
when an API or endpoint is going away? 


t.io 


How-To: 

Compelling blog post on 
deprecating API endpoints by 
the Stoplight.io team 
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